1 Loading

Loading a file of Lisp code means bringing its contents into the Lisp environment in the form of Lisp objects. Emacs finds and opens the file, reads the text, evaluates each form, and then closes the file.

The load functions evaluate all the expressions in a file just as the eval-current-buffer function evaluates all the expressions in a buffer. The difference is that the load functions read and evaluate the text in the file as found on disk, not the text in an Emacs buffer.

The loaded file must contain Lisp expressions, either as source code or, optionally, as byte-compiled code. Each form in the file is called a top-level form. There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions.

A file containing Lisp code is often called a library. Thus, the “Rmail library” is a file containing code for Rmail mode. Similarly, a “Lisp library directory” is a directory of files containing Lisp code.

1.1 How Programs Do Loading

There are several interface functions for loading. For example, the autoload function creates a Lisp object that loads a file when it is evaluated (see section Autoload). require also causes files to be loaded (see section Features). Ultimately, all these facilities call the load function to do the work.

Function: load filename &optional missing-ok nomessage nosuffix

This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file.

To find the file, load first looks for a file named ‘filename.elc’, that is, for a file whose name has ‘.elc’ appended. If such a file exists, it is loaded. But if there is no file by that name, then load looks for a file whose name has ‘.el’ appended. If that file exists, it is loaded. Finally, if there is no file by either name, load looks for a file named filename with nothing appended, and loads it if it exists. (The load function is not clever about looking at filename. In the perverse case of a file named ‘foo.el.el’, evaluation of (load "foo.el") will indeed find it.)

If the optional argument nosuffix is non-nil, then the suffixes ‘.elc’ and ‘.el’ are not tried. In this case, you must specify the precise file name you want.

If filename is a relative file name, such as ‘foo’ or ‘baz/foo.bar’, load searches for the file using the variable load-path. It appends filename to each of the directories listed in load-path, and loads the first file it finds whose name matches. The current default directory is tried only if it is specified in load-path, where it is represented as nil. All three possible suffixes are tried in the first directory in load-path, then all three in the second directory in load-path, etc.

If you get a warning that ‘foo.elc’ is older than ‘foo.el’, it means you should consider recompiling ‘foo.el’. @xref{Byte Compilation}.

Messages like ‘Loading foo...’ and ‘Loading foo...done’ appear in the echo area during loading unless nomessage is non-nil.

Any errors that are encountered while loading a file cause load to abort. If the load was done for the sake of autoload, certain kinds of top-level forms, those which define functions, are undone.

The error file-error is signaled (with ‘Cannot open load file filename’) if no file is found. No error is signaled if missing-ok is non-nil—then load just returns nil.

load returns t if the file loads successfully.

User Option: load-path

The value of this variable is a list of directories to search when loading files with load. Each element is a string (which must be a directory name) or nil (which stands for the current working directory). The value of load-path is initialized from the environment variable EMACSLOADPATH, if it exists; otherwise it is set to the default specified in ‘emacs/src/paths.h’ when Emacs is built.

The syntax of EMACSLOADPATH is the same as that of PATH; fields are separated by ‘:’, and ‘.’ is used for the current default directory. Here is an example of how to set your EMACSLOADPATH variable from a csh ‘.login’ file:

setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp

Here is how to set it using sh:

export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp

Here is an example of code you can place in a ‘.emacs’ file to add several directories to the front of your default load-path:

(setq load-path
      (append
       (list nil
             "/user/bil/emacs"
             "/usr/local/lisplib")
       load-path))

In this example, the path searches the current working directory first, followed then by the ‘/user/bil/emacs’ directory and then by the ‘/usr/local/lisplib’ directory, which are then followed by the standard directories for Lisp code.

When Emacs version 18 processes command options ‘-l’ or ‘-load’ which specify Lisp libraries to be loaded, it temporarily adds the current directory to the front of load-path so that files in the current directory can be specified easily. Newer Emacs versions also find such files in the current directory, but without altering load-path.

Variable: load-in-progress

This variable is non-nil if Emacs is in the process of loading a file, and it is nil otherwise. This is how defun and provide determine whether a load is in progress, so that their effect can be undone if the load fails.

To learn how load is used to build Emacs, see @ref{Building Emacs}.

1.2 Autoload

The autoload facility allows you to make a function or macro available but put off loading its actual definition. An attempt to call a symbol whose definition is an autoload object automatically reads the file to install the real definition and its other associated code, and then calls the real definition.

To prepare a function or macro for autoloading, you must call autoload, specifying the function name and the name of the file to be loaded. A file such as ‘emacs/lisp/loaddefs.el’ usually does this when Emacs is first built.

The following example shows how doctor is prepared for autoloading in ‘loaddefs.el’:

(autoload 'doctor "doctor"
  "\
Switch to *doctor* buffer and start giving psychotherapy."
  t)

The backslash and newline immediately following the double-quote are a convention used only in the preloaded Lisp files such as ‘loaddefs.el’; they cause the documentation string to be put in the ‘etc/DOC’ file. (@xref{Building Emacs}.) In any other source file, you would write just this:

(autoload 'doctor "doctor"
  "Switch to *doctor* buffer and start giving psychotherapy."
  t)

Calling autoload creates an autoload object containing the name of the file and some other information, and makes this the function definition of the specified symbol. When you later try to call that symbol as a function or macro, the file is loaded; the loading should redefine that symbol with its proper definition. After the file completes loading, the function or macro is called as if it had been there originally.

If, at the end of loading the file, the desired Lisp function or macro has not been defined, then the error error is signaled (with data "Autoloading failed to define function function-name").

The autoloaded file may, of course, contain other definitions and may require or provide one or more features. If the file is not completely loaded (due to an error in the evaluation of the contents) any function definitions or provide calls that occurred during the load are undone. This is to ensure that the next attempt to call any function autoloading from this file will try again to load the file. If not for this, then some of the functions in the file might appear defined, but they may fail to work properly for the lack of certain subroutines defined later in the file and not loaded successfully.

Emacs as distributed comes with many autoloaded functions. The calls to autoload are in the file ‘loaddefs.el’. There is a convenient way of updating them automatically.

Write ‘;;;###autoload’ on a line by itself before a function definition before the real definition of the function, in its autoloadable source file; then the command M-x update-file-autoloads automatically puts the autoload call into ‘loaddefs.el’. M-x update-directory-autoloads is more powerful; it updates autoloads for all files in the current directory.

You can also put other kinds of forms into ‘loaddefs.el’, by writing ‘;;;###autoload’ followed on the same line by the form. M-x update-file-autoloads copies the form from that line.

The commands for updating autoloads work by visiting and editing the file ‘loaddefs.el’. To make the result take effect, you must save that file’s buffer.

Function: autoload symbol filename &optional docstring interactive type

This function defines the function (or macro) named symbol so as to load automatically from filename. The string filename is a file name which will be passed to load when the function is called.

The argument docstring is the documentation string for the function. Normally, this is the same string that is in the function definition itself. This makes it possible to look at the documentation without loading the real definition.

If interactive is non-nil, then the function can be called interactively. This lets completion in M-x work without loading the function’s real definition. The complete interactive specification need not be given here. If type is macro, then the function is really a macro. If type is keymap, then the function is really a keymap.

If symbol already has a non-nil function definition that is not an autoload object, autoload does nothing and returns nil. If the function cell of symbol is void, or is already an autoload object, then it is set to an autoload object that looks like this:

(autoload filename docstring interactive type)

For example,

(symbol-function 'run-prolog)
     ⇒ (autoload "prolog" 169681 t nil)

In this case, "prolog" is the name of the file to load, 169681 refers to the documentation string in the ‘emacs/etc/DOC’ file (@pxref{Documentation Basics}), t means the function is interactive, and nil that it is not a macro.

1.3 Repeated Loading

You may load a file more than once in an Emacs session. For example, after you have rewritten and reinstalled a function definition by editing it in a buffer, you may wish to return to the original version; you can do this by reloading the file in which it is located.

When you load or reload files, bear in mind that the load and load-library functions automatically load a byte-compiled file rather than a non-compiled file of similar name. If you rewrite a file that you intend to save and reinstall, remember to byte-compile it if necessary; otherwise you may find yourself inadvertently reloading the older, byte-compiled file instead of your newer, non-compiled file!

When writing the forms in a library, keep in mind that the library might be loaded more than once. For example, the choice of defvar vs. defconst for defining a variable depends on whether it is desirable to reinitialize the variable if the library is reloaded: defconst does so, and defvar does not. (@xref{Defining Variables}.)

The simplest way to add an element to an alist is like this:

(setq minor-mode-alist
      (cons '(leif-mode " Leif") minor-mode-alist))

But this would add multiple elements if the library is reloaded. To avoid the problem, write this:

(or (assq 'leif-mode minor-mode-alist)
    (setq minor-mode-alist
          (cons '(leif-mode " Leif") minor-mode-alist)))

Occasionally you will want to test explicitly whether a library has already been loaded; you can do so as follows:

(if (not (boundp 'foo-was-loaded))
    execute-first-time-only)

(setq foo-was-loaded t)

1.4 Features

provide and require are an alternative to autoload for loading files automatically. They work in terms of named features. Autoloading is triggered by calling a specific function, but a feature is loaded the first time another program asks for it by name.

The use of named features simplifies the task of determining whether required definitions have been defined. A feature name is a symbol that stands for a collection of functions, variables, etc. A program that needs the collection may ensure that they are defined by requiring the feature. If the file that contains the feature has not yet been loaded, then it will be loaded (or an error will be signaled if it cannot be loaded). The file thus loaded must provide the required feature or an error will be signaled.

To require the presence of a feature, call require with the feature name as argument. require looks in the global variable features to see whether the desired feature has been provided already. If not, it loads the feature from the appropriate file. This file should call provide at the top-level to add the feature to features.

Features are normally named after the files they are provided in so that require need not be given the file name.

For example, in ‘emacs/lisp/prolog.el’, the definition for run-prolog includes the following code:

(defun run-prolog ()
  "Run an inferior Prolog process,\
 input and output via buffer *prolog*."
  (interactive)
  (require 'comint)
  (switch-to-buffer (make-comint "prolog" prolog-program-name))
  (inferior-prolog-mode))

The expression (require 'shell) loads the file ‘shell.el’ if it has not yet been loaded. This ensures that make-shell is defined.

The ‘shell.el’ file contains the following top-level expression:

(provide 'shell)

This adds shell to the global features list when the ‘shell’ file is loaded, so that (require 'shell) will henceforth know that nothing needs to be done.

When require is used at top-level in a file, it takes effect if you byte-compile that file (@pxref{Byte Compilation}). This is in case the required package contains macros that the byte compiler must know about.

Although top-level calls to require are evaluated during byte compilation, provide calls are not. Therefore, you can ensure that a file of definitions is loaded before it is byte-compiled by including a provide followed by a require for the same feature, as in the following example.

(provide 'my-feature)  ; Ignored by byte compiler,
                       ;   evaluated by load.
(require 'my-feature)  ; Evaluated by byte compiler.

Function: provide feature

This function announces that feature is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with feature are or will be available for other Lisp programs.

The direct effect of calling provide is to add feature to the front of the list features if it is not already in the list. The argument feature must be a symbol. provide returns feature.

features
     ⇒ (bar bish)

(provide 'foo)
     ⇒ foo
features
     ⇒ (foo bar bish)

During autoloading, if the file is not completely loaded (due to an error in the evaluation of the contents) any function definitions or provide calls that occurred during the load are undone. See section Autoload.

Function: require feature &optional filename

This function checks whether feature is present in the current Emacs session (using (featurep feature); see below). If it is not, then require loads filename with load. If filename is not supplied, then the name of the symbol feature is used as the file name to load.

If feature is not provided after the file has been loaded, Emacs will signal the error error (with data ‘Required feature feature was not provided’).

Function: featurep feature

This function returns t if feature has been provided in the current Emacs session (i.e., feature is a member of features.)

Variable: features

The value of this variable is a list of symbols that are the features loaded in the current Emacs session. Each symbol was put in this list with a call to provide. The order of the elements in the features list is not significant.

1.5 Unloading

You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function unload-feature:

Command: unload-feature feature

This command unloads the library that provided feature feature. It undefines all functions and variables defined with defvar, defmacro, defconst, defsubst and defalias by the library which provided feature feature. It then restores any autoloads associated with those symbols.

The unload-feature function is written in Lisp; its actions are based on the variable load-history.

Variable: load-history feature association list

This variable’s value is an alist connecting library names with the names of functions and variables they define, the features they provide, and the features they require.

Each element is a list and describes one library. The CAR of the list is the name of the library, as a string. The rest of the list is composed of these kinds of objects:

• Symbols, which were defined as functions or variables.
• Lists of the form (require . feature) indicating the features that are required.
• Lists of the form (provide . feature) indicating the features that are provided.

The value of load-history may have one element whose CAR is nil. This element describes definitions made with eval-buffer on a buffer that is not visiting a file.

The command eval-region updates load-history, but does so by adding the symbols defined to the element for the file being visited, rather than replacing that element.

1.6 Hooks for Loading

You can ask for code to be executed if and when a particular library is loaded, by calling eval-after-load.

Function: eval-after-load library form

This function arranges to evaluate form at the end of loading the library library, if and when library is loaded.

The library name library must exactly match the argument of load. To get the proper results when an installed library is found by searching load-path, you should not include any directory names in library.

An error in form does not undo the load, but does prevent execution of the rest of form.

Variable: after-load-alist

An alist of expressions to evaluate if and when particular libraries are loaded. Each element looks like this:

(filename forms…)

The function load checks after-load-alist in order to implement eval-after-load.

About This Document

This document was generated on January 16, 2023 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on January 16, 2023 using texi2html 5.0.